1. Field of Invention
This invention relates to rationale capture, specifically rationales for decisions, recommendations, plans, or specifications described in a document.
2. Background of the Invention
The problem that this invention addresses is the loss of contextual knowledge when decisions or recommendations are made and documented. The problem spans a wide range of activities, including                engineering design        software development        business, organizational, and other forms of planning        training and instruction        
Any time that a document is created in order to record and communicate a set of decisions or recommendations, there is also a need to record the rationale for the recommendations, explanations of the meaning and consequences of the recommendations, and commentary about the context in which they are made. This need applies both to decisions that have already been implemented, as in documenting software code, and to recommendations for future activity, as in designs, plans, and instructional documents.
The costs of not capturing rationale and related commentary are well known. When software must be maintained, if the rationales for its current design and code are missing, changes are likely to introduce errors that are costly to discover and fix. Insufficient documentation of alternatives that were considered and rejected can lead to maintainers “reinventing the wheel” by going down the already considered paths. When training manuals lack sufficient context, operators learning from them are likely to draw incorrect generalizations or conclusions, which in the case of safety- or life-critical systems can have catastrophic results. Budgets defined in a spreadsheet without comments providing the rationale for various estimates of income and expense can lead to poor management decisions if the conditions on which the estimates were based change.
Despite the known costs of not capturing rationale, it is frequently not done at all, or done as an afterthought. Knowledge workers tend to resist the requirement to document their rationale. This phenomenon can be understood in terms of the perceived cost of, and motivation for, the rationale capture activity. The cost of rationale capture can be measured in terms of the additional effort, or overhead, required of the document author. This perceived cost is correlated with the time required to document the additional information. Time is consumed in two ways, (1) the formulation of cogent rationales and (2) the recording process itself. The time required to perform these activities is a function of the cognitive, sensory, and motor demands that the activities place upon the author. The first activity, formulation of rationales, primarily imposes cognitive demand on the author. The second activity, recording the rationale, imposes not just cognitive but also sensory and motor demand. For example, the author must decide on the location, form, and style of the rationale documentation—relating it, for example, to other recorded rationales; this imposes cognitive demands. Sensory and motor demands are imposed by the tools, such as word processors or other computer-based tools, that are used to record the rationales.
Previous attempts to foster documentation of rationale and commentary include tools specifically intended for rationale capture, such as WinWin (Horowitz, E., Lee, J. H., and Lee, J. S., “WinWin: a System for Negotiating Requirements”, Proceedings of the 21st International Conference on Software Engineering, Los Angeles, Calif., May 16-22, 1999, IEEE Computer Society Press, pages: 646-649); argument documentation systems such as Issue-Based Information System (Conklin, J. and Begeman, M. L., “gIBIS: A Hypertext Tool for Exploratory Policy Discussion”, ACM Transactions on Office Information Systems, 6(4):303-331, October 1988), and U.S. Pat. No. 5,784,286; software program comment authoring and display tools such as that described in U.S. Pat. No. 5,513,305, and my own system entitled Better Elicitation and Communication of Arguments Underlying Software Engineering, or BECAUSE (NASA Tech Briefs, September 2002, KSC-12339); and general document authoring tools that provide for comments and annotations to a main text, such as those described in U.S. Pat. No. 5,806,079 and U.S. Pat. No. 6,389,434.
Experiences with such tools have demonstrated that even the slightest additional overhead, including the need to interact with a special rationale capture tool, can dissuade the author from recording rationales. Authors frequently intend merely to postpone the process, fully intending to return to the document later in order to record rationales and commentary. However, under time and task pressures, these intentions are often left unrealized.
The overhead disincentive has proven to be a problem with all of the tools identified above. Tools intended specifically for rationale capture, such as WinWin, gIBIS, and U.S. Pat. No. 5,784,286, provide ways of structuring and organizing rationale, but they operate separately from the authoring tools in which the product being explained is actually documented, e.g., the software code, planning spreadsheet, design specification, or instructional text whose rationale is being captured. The need to use a separate tool introduces enough overhead in the rationale capture process to dissuade most knowledge workers from bothering.
Some word processors and other document authoring tools, such as Microsoft Word, provide a comment or annotation mechanism whereby comments can be associated with particular locations in the main document text. The comments appear as separate items, for example as pop-up post-in notes, attached to the corresponding locations of the main text.
Even if a special comment-attachment or annotation feature is not available, ordinary text editors can be used to document rationale and provide comments on a main text. Various formatting conventions may be applied to distinguish commentary from the main text. For example, in software code, comments are explicitly marked by a sequence of characters that are reserved for this purpose by the programming language.
All of these authoring tools, however, suffer from the problem that commentary and main text are input through the same devices, usually keyboard and mouse, using the same motor skills of the operator. This means that the two activities, (1) authoring the main content of the document, and (2) providing comments, compete against each other for the attention of the operator. For example, typing numerical budget estimates into a spreadsheet competes with typing in explanations of the estimates. Under time pressure, it is the explanations that will most likely be omitted.
The BECAUSE system attempted to solve this problem by using two distinct input streams, one for the principal content of the document, which in that case was computer program source code, and one for the commentary. Specifically, BECAUSE captured spoken comments through a microphone, so that the software developer could type code and concurrently speak an explanation of what he was typing, and both inputs would appear in the resulting code, with the spoken words converted into program comments.
Despite the advance of capturing spoken comments, BECAUSE was limited in several respects that caused it to fall short of truly non-intrusive comment capture. BECAUSE makes essential use of a comment capture panel, which is a separate window in which the spoken comments are displayed after being converted from voice to text. This capture window is distinct from the window in which the source code is being created or edited. Its presence draws the user's attention away from the primary task of programming. Furthermore, comments are moved from the capture window to the program code only upon an explicit user command. This reduces the naturalness of the speech process and further shifts the user's attention away from the primary task of programming.
BECAUSE relies on the comment capture window and the explicit user command to begin insertion because it lacks any logic for maintaining and managing the links between comments and program code. Instead, it relies on the insertion of comments near the corresponding program code to establish the linkage visually. Visual proximity is a valid method for displaying the connection between a comment and the code to which it refers, but the lack of any additional link management forces BECAUSE to rely on explicit user insert commands to indicate when insertion should occur. This, in turn, forces the use of the separate comment capture window.
To see why this is so, consider what would happen if BECAUSE were to insert comments immediately into the program code, without waiting for a user command to do so. The result would be a display of the program code that was continually moving and changing visual shape. For example, the location at which the user was typing would suddenly shift down the screen when a comment was automatically inserted. This would constitute an unacceptably unstable user interface. It was to mitigate this problem that BECAUSE resorted to the explicit user command to insert the comment. This reliance on user commands, in turn, forces BECAUSE to present the captured comments in a separate window prior to insertion.
The limitations of BECAUSE in achieving truly non-intrusive comment capture stem from the absence of logic for maintaining and managing the links between comments and code. To improve upon this situation, the Commentary Capture Machine described in this application includes a memory controller whose job is precisely to maintain and manage the linkage between comments and primary content. This management is performed “behind the scenes” and is transparent to the user. The existence of the memory controller allows the machine to decouple the creation of comment-to-content links from the display of the comments. This, in turn, enables the machine to choose appropriate times to insert the comments, if insertion is the desired method for display. In addition, the machine provides alternative display mechanisms, including icons representing the presence of a comment, pop-up display of comments, and hyperlinks. The memory controller, in combination with the variety of display mechanisms, enables the machine to avoid the unstable display problem in a less intrusive, more transparent manner than BECAUSE.
The Commentary Capture Machine is distinguished by several advantages, for purposes of document commentary capture, over the invention described in U.S. Pat. No. 6,665,490. That invention provides a way to annotate recordings either during the recording process itself or while the recording is being played. The annotations in that invention, however, are manual, i.e., performed through handwriting or typing at a keyboard. In addition, that invention applies only to “recordings,” which are defined as “information that is stored over time and can be replayed over time.” By contrast, the Commentary Capture Machine described in this application facilitates comment capture by voice or other input means, for any form of computerized document. This includes documents where there is no direct correlation between elements of the document and their time-of-creation or time-of-display, and which therefore cannot be treated as recordings in the sense of U.S. Pat. No. 6,665,490.
The inventions described in U.S. Pat. No. 6,675,352 provides for voice annotations, but does not automatically attach the annotation to the document in an appropriate location, relying instead on explicit manually created “annotation commands.” It therefore does not achieve the level of non-intrusiveness achieved by the Commentary Capture Machine. The invention described in U.S. Pat. No. 6,671,684 provides for simultaneous physical and electronic highlighting of portions of a document, where the electronic highlighting is achieved by electronically scanning the manual highlighting. This too requires manual input of the highlighting, thus falling short of the level of non-intrusiveness achieved by the Commentary Capture Machine. In addition, the Commentary Capture Machine captures comments and annotations in general, i.e., verbal statements explaining the primary content of the document, rather than just highlights, which may be considered a specific form of annotation.